<!-- HTML header for doxygen 1.8.4-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
		<meta http-equiv="X-UA-Compatible" content="IE=9"/>
		<meta name="generator" content="Doxygen 1.8.4"/>
		<title>exceptions4c: Main Page</title>
		<link href="tabs.css" rel="stylesheet" type="text/css"/>
		<link href="exceptions4c.css" rel="stylesheet" type="text/css" />
		<!-- <link href="sheep_016.png" rel="shortcut icon" /> -->
		<link href="" rel="shortcut icon">
		<script type="text/javascript" src="jquery.js"></script>
		<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
		<link href="exceptions4c.css" rel="stylesheet" type="text/css" />
	</head>
	<body>
		<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
				<div id="titlearea">
					<table cellspacing="0" cellpadding="0">
						<tbody>
							<tr style="height: 56px;">
									<td id="projectlogo"><img alt="Logo" src="sheep_064.png"/></td>
									<td style="padding-left: 0.5em;">
										<div id="projectname">
											exceptions4c
											&nbsp;
											<span id="projectnumber">version 3.0</span>
										</div>
											<div id="projectbrief">An exception handling framework for C</div>
									</td>
							</tr>
						</tbody>
				</table>
			</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.4 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="contents">
<div class="textblock"><h1>exceptions4c Reference Documentation</h1>
<div class="image">
<img src=""  alt="exceptions4c" height="64" width="64"/>
</div>
 <h1><a class="anchor" id="e4c"></a>
exceptions4c</h1>
<dl class="section version"><dt>Version</dt><dd>3.0 </dd></dl>
<dl class="section author"><dt>Author</dt><dd>Copyright (c) 2013 Guillermo Calvo </dd></dl>
<dl class="section see"><dt>See Also</dt><dd><a href="http://code.google.com/p/exceptions4c/">http://code.google.com/p/exceptions4c/</a></dd></dl>
<h1><a class="anchor" id="home"></a>
An exception handling framework for C</h1>
<p><b>Bring the power of exceptions to your C applications with this tiny, portable exception handling framework!</b></p>
<p>This library provides you with a simple set of keywords (<em>macros</em>, actually) which map the semantics of exception handling you're probably already used to:</p>
<ul>
<li><code><a class="el" href="e4c_8h.html#a28599e8ac99ea9faff60a2258a914aee" title="Introduces a block of code aware of exceptions. ">try</a></code></li>
<li><code><a class="el" href="e4c_8h.html#a629585c5169ebdb440b9015f8e87b4df" title="Introduces a block of code capable of handling a specific type of exceptions. ">catch</a></code></li>
<li><code><a class="el" href="e4c_8h.html#a6f547472794c162cc629f53cd4db5454" title="Introduces a block of code responsible for cleaning up the previous exception-aware block...">finally</a></code></li>
<li><code><a class="el" href="e4c_8h.html#a482d649fcaafd28584629da3606e4ea7" title="Signals an exceptional situation represented by an exception object. ">throw</a></code></li>
</ul>
<p>You can write <code><a class="el" href="e4c_8h.html#a28599e8ac99ea9faff60a2258a914aee" title="Introduces a block of code aware of exceptions. ">try</a></code>... <code><a class="el" href="e4c_8h.html#a629585c5169ebdb440b9015f8e87b4df" title="Introduces a block of code capable of handling a specific type of exceptions. ">catch</a></code>... <code><a class="el" href="e4c_8h.html#a6f547472794c162cc629f53cd4db5454" title="Introduces a block of code responsible for cleaning up the previous exception-aware block...">finally</a></code> blocks just as if you were coding in Java:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> foo;</div>
<div class="line"><span class="keywordtype">void</span> * buffer = malloc(1024);</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">try</span>{</div>
<div class="line">    foo = bar(buffer);</div>
<div class="line">}<span class="keywordflow">catch</span>(BadUserInputException){</div>
<div class="line">    foo = 123;</div>
<div class="line">}<span class="keywordflow">finally</span>{</div>
<div class="line">    free(buffer);</div>
<div class="line">}</div>
</div><!-- fragment --><p>This way you will never have to deal again with boring error codes, or check return values every time you call a function.</p>
<h1><a class="anchor" id="hierarchies"></a>
Exception Hierarchies</h1>
<p>The possible <a class="el" href="structe4c__exception.html">exceptions</a> in a program are organized in a <em>pseudo-hierarchy</em> of exceptions. <code><a class="el" href="e4c_8h.html#a07da936a74602281d601c171b77bf0b0" title="This is the root of the exception pseudo-hierarchy ">RuntimeException</a></code> is the root of the exceptions <em>pseudo-hierarchy</em>. <b>Any exception</b> can be handled by a code block introduced by <code><a class="el" href="e4c_8h.html#a629585c5169ebdb440b9015f8e87b4df" title="Introduces a block of code capable of handling a specific type of exceptions. ">catch(RuntimeException)</a></code>, <b>except for <code><a class="el" href="e4c_8h.html#a64df4b96937a949466d55b5638c5b9cf" title="This exception is thrown when an assertion does not hold. ">AssertionException</a></code></b>.</p>
<p>When an exception is thrown, control is transferred to the nearest dynamically-enclosing <code>catch</code> code block that handles the exception. Whether a particular <code>catch</code> block handles an exception is found out by comparing the <b>type</b> (and <em>supertypes</em>) of the actual thrown exception against the specified exception type in the <code>catch</code> clause.</p>
<p>A <code>catch</code> block is given an <b>exception type</b> as a parameter. This parameter determines the set of exceptions that can be handled by the code block. A block handles an actual exception that was thrown if the specified type parameter is either:</p>
<ul>
<li>the same type of that exception.</li>
<li>the same type of any of the <em>supertypes</em> of that exception.</li>
</ul>
<p>If you write a <code>catch</code> block that handles an exception with no defined <em>subtypes</em>, it will only handle that very specific exception. By grouping exceptions into <em>hierarchies</em>, you can design generic <code>catch</code> blocks that deal with several exceptions.</p>
<h1><a class="anchor" id="dispose"></a>
Dispose Pattern</h1>
<p>There are other keywords related to resource handling:</p>
<ul>
<li><code><a class="el" href="e4c_8h.html#a4afea611dbbe18fc3e3665166b3cd7bc" title="Opens a block of code with automatic disposal of a resource. ">with</a></code>... <code><a class="el" href="e4c_8h.html#aeda5446032a08fece73ec569b861a72c" title="Closes a block of code with automatic disposal of a resource. ">use</a></code></li>
<li><code><a class="el" href="e4c_8h.html#abe1fc0d5310579fdfe7cca02506d06c2" title="Introduces a block of code with automatic acquisition and disposal of a resource. ...">using</a></code></li>
</ul>
<p>They allow you to express the <em>Dispose Pattern</em> in your code:</p>
<div class="fragment"><div class="line">FOO foo;</div>
<div class="line"><a class="code" href="e4c_8h.html#a4afea611dbbe18fc3e3665166b3cd7bc" title="Opens a block of code with automatic disposal of a resource. ">with</a>(foo, dispose_FOO) foo = acquire_FOO(bar, foobar); <a class="code" href="e4c_8h.html#aeda5446032a08fece73ec569b861a72c" title="Closes a block of code with automatic disposal of a resource. ">use</a> do_something(foo);</div>
<div class="line"></div>
<div class="line">...</div>
<div class="line"></div>
<div class="line">BAR bar;</div>
<div class="line"><a class="code" href="e4c_8h.html#abe1fc0d5310579fdfe7cca02506d06c2" title="Introduces a block of code with automatic acquisition and disposal of a resource. ...">using</a>(BAR, bar, (&quot;BAR&quot;, 123) ){</div>
<div class="line">    do_something_else(bar);</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line">...</div>
<div class="line"></div>
<div class="line">FILE * file;</div>
<div class="line"><a class="code" href="e4c__rsc_8h.html#ab95c95244edfd564ed80fb5425e80ec5" title="Introduces a block of code with automatic acquisition and disposal of a file stream. ">e4c_using_file</a>(file, <span class="stringliteral">&quot;log.txt&quot;</span>, <span class="stringliteral">&quot;a&quot;</span>){</div>
<div class="line">    fputs(<span class="stringliteral">&quot;hello, world!\n&quot;</span>, file);</div>
<div class="line">}</div>
</div><!-- fragment --><p>This is a clean and terse way to handle all kinds of resources with implicit acquisition and automatic disposal.</p>
<h1><a class="anchor" id="signals"></a>
Signal Handling</h1>
<p>In addition, signals (such as <code>SIGHUP</code>, <code>SIGFPE</code> and <code>SIGSEGV</code>) can be handled in an <em>exceptional way</em>. Forget about scary segmentation faults, all you need to do is <em>catch</em> <code><a class="el" href="e4c_8h.html#aae2c0f060628a75c117ff4bf75f2804f" title="This exception is thrown when the process tries to dereference an invalid pointer. ">BadPointerException</a></code>:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> * pointer = NULL;</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">try</span>{</div>
<div class="line">    <span class="keywordtype">int</span> oops = *pointer;</div>
<div class="line">}<span class="keywordflow">catch</span>(BadPointerException){</div>
<div class="line">    printf(<span class="stringliteral">&quot;No problem ;-)&quot;</span>);</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="threads"></a>
Multithreading</h1>
<p>If you are using threads in your program, you must switch on the <em>thread-safe</em> version of the library by defining <code>E4C_THREADSAFE</code> at compiler level.</p>
<p>The usage of the framework does not vary between single- and multi-threaded programs. The same semantics apply. The only caveat is that, by definition, <b>the behaviour of signal handling is undefined in a multithreaded program</b>, so use this feature with caution.</p>
<h1><a class="anchor" id="integration"></a>
Integration</h1>
<p>Whether you are developing a standalone application, or an external library that provides services to independent programs, you can integrate <b>exceptions4c</b> in your code very easily.</p>
<p>The system provides a mechanism for implicit initialization and finalization of the exception framework, so that it is safe to use <code>try</code>, <code>catch</code>, <code>throw</code>, etc. from any external function, even if the rest of the program does not leverage the exception system at all.</p>
<h1><a class="anchor" id="portability"></a>
Portability</h1>
<p>This library should compile in any <b>ANSI C</b> compiler. It uses nothing but standard C functions. In order to use <b>exceptions4c</b> you have to drop the two files (<code><a class="el" href="e4c_8h.html" title="exceptions4c header file ">e4c.h</a></code> and <code>e4c.c</code>) in your project and remember to include the header file from your code. That's all.</p>
<p>In case your application uses threads, <b>exceptions4c</b> relies on <b>pthreads</b>, the <b>POSIX</b> application programming interface for writing multithreaded applications. This <em>API</em> is available for most operating systems and platforms.</p>
<h1><a class="anchor" id="lightweight"></a>
Lightweight Version</h1>
<p>If you have the feeling that the standard version of <b>exceptions4c</b> may be <em>a bit overkill</em> for your specific needs, there exists a <a href="https://code.google.com/p/exceptions4c/wiki/lite">lightweight version</a>, targeted at small projects and embedded systems. Use it when you just want to handle error conditions that may occur in your program through a simple yet powerful exception handling mechanism. It provides the <b>core functionality of exceptions4c in less than 200 source lines of code</b>.</p>
<h1><a class="anchor" id="software_license"></a>
Software License</h1>
<blockquote class="doxtable">
<p>This is free software: you can redistribute it and/or modify it under the terms of the <b>GNU Lesser General Public License</b> as published by the <em>Free Software Foundation</em>, either version 3 of the License, or (at your option) any later version.</p>
<p>This software is distributed in the hope that it will be useful, but <b>WITHOUT ANY WARRANTY</b>; without even the implied warranty of <b>MERCHANTABILITY</b> or <b>FITNESS FOR A PARTICULAR PURPOSE</b>. See the <a href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public License</a> for more details.</p>
<p>You should have received a copy of the GNU Lesser General Public License along with this software. If not, see <a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>.</p>
<p></p>
</blockquote>
<dl class="section user"><dt>Required:</dt><dd><ul>
<li><b>License and copyright notice</b>: Include a copy of the license and copyright notice with the code.</li>
<li><b>Library usage</b>: The library may be used within a non-open-source application.</li>
<li><b>Disclose Source</b>: Source code for this library must be made available when distributing the software.</li>
</ul>
</dd></dl>
<dl class="section user"><dt>Permitted:</dt><dd><ul>
<li><b>Commercial Use</b>: This software and derivatives may be used for commercial purposes.</li>
<li><b>Modification</b>: This software may be modified.</li>
<li><b>Distribution</b>: You may distribute this software.</li>
<li><b>Sublicensing</b>: You may grant a sublicense to modify and distribute this software to third parties not included in the license.</li>
<li><b>Patent Grant</b>: This license provides an express grant of patent rights from the contributor to the recipient.</li>
</ul>
</dd></dl>
<dl class="section user"><dt>Forbidden:</dt><dd><ul>
<li><b>Hold Liable</b>: Software is provided without warranty and the software author/license owner cannot be held liable for damages.</li>
</ul>
</dd></dl>
<h1><a class="anchor" id="documentation_license"></a>
Documentation License</h1>
<blockquote class="doxtable">
<p>Permission is granted to copy, distribute and/or modify this document under the terms of the <b>GNU Free Documentation License</b>, Version 1.3 or any later version published by the <em>Free Software Foundation</em>; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. See the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License</a> for more details. </p>
</blockquote>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.4-->
<!-- start footer part -->
			<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
			  <ul>
				<li class="footer">
					<a href="https://code.google.com/p/exceptions4c/" title="exceptions4c version 3.0">
						<img src="sheep_016.png" width="16" height="16" alt="" style="vertical-align: text-bottom;" />
						<strong>exceptions4c</strong>
					</a>
					Reference Documentation
					Generated by
					<a href="http://www.doxygen.org/index.html" title="doxygen 1.8.4">
						<strong>doxygen</strong>
					</a>
				</li>
			  </ul>
			</div>
	</body>
</html>
